ParcelAddress API

(0 reviews)

Search for International Address

Resource URL

UAT:

https://api.uat.nzpost.co.nz/parceladdress/2.0/international/addresses

Production:

https://api.nzpost.co.nz/parceladdress/2.0/international/addresses

Resource Description

Returns a list of suggested addresses for a given country code and address fragment. This resource is ![Alt text](https://developers.google.com/places/documentation/images/powered-by-google-on-white.png).

Resource Information

Attribute	Detail
Response Format	JSON
Requires Authentication	Yes
Rate Limited	15 calls per second. If rate limit is exceeded, calls will be queued. Calls unprocessed for over 60 seconds will time out.

Please note that all request parameters should be in lower case.

Request Parameters

Field Name	Description	Mand	Example
country_code	Country code for address country	No	US
count	The maximum number of matching results to be returned	Yes	5
q	Address fragment to search for suggestions	Yes	3800 LaPasa

Country Code

Valid country codes can be found here. In the future, a method will be provided that will return a complete and up-to-date list of country codes.

Sample Request

https://api.nzpost.co.nz/parceladdress/2.0/international/addresses?q=38%20Lap&count=5&country_code=US

Business Rules

The following business rules are applied on each international/addresses request:

Name	Description
BR001	The address fragment (parameter ‘q’) must contain at least 4 characters after the leading and following spaces are removed by the API code. If less than 4 characters, an error message will be returned to the requester.
BR002	If no count value is provided, a default number of responses is returned. The default is set to 5 records.
BR003	If the count value provided is greater than 5 and there are more than 5 addresses matching the address fragment, only 5 address records will be returned to the merchant.

Response Parameters

The following lists the required fields in the /addresses response message.

Field Name	Description	Mand	Example
success	Returns if request is successful	Yes	false
addresses	Contains array of address objects. The number of object will not exceed the ‘Count’ value defined.	Y if success = true	"addresses":[]

Address Object

The following lists the fields in the address object.

Field Name	Description	Mand	Example
address_id	A unique id for representing the address	Yes	EjAzODAwIExhIFBhc2FkYSBBdmUsIExhcyBWZWdhcywgTlYsIFVuaXRlZCBTdGF0ZXM
full_address	Human-readable format of the address	Yes if success = true	3800 La Pasada Ave, Las Vegas, NV 89102, USA

Error Response Elements

Field Name	Description	Mand	Example
success	Returns if request is successful	Yes	false
errors	Error object with error details	Yes if success =false	See Error Object Parameters below
message_id	The unique message identifier	Yes	ec608f40-2a8b-11e5-a9c0-025c481d35ef

Error Object Parameters

Field Name	Description	Example
code	Error code where first 3 digits are http status code, last three digits identify error type	400002
message	Description of error code	Invalid Parameter(s)
details	Description of specific error	Address prefix must be at least 4 characters, not including spaces at the beginning or end.

HTTP Status Codes

Note that some error messages are customised for the request, i.e. error code 400 usually will describe what is wrong with the request

Code	Message
200	Success
400	Bad request
401	Unauthorized
403	Forbidden
409	Invalid request
500	System unavailable

Error Codes

Code	Message
200001	Partial results returned, not all system(s) have responded
200002	All sources responded, data may be incomplete
400001	Parameter(s) missing
400002	Invalid parameter(s)
400003	Non mutually exclusive parameters detected
401001	Unauthorised access, please contact administrator
500001	General Exception
500002	System(s) offline

Sample Response

Sample:


{
   "success": true,
   "addresses":    [
            {
         "full_address": "38 Lapstone Street, The Ponds, New South Wales, Australia",
         "address_id": "EjkzOCBMYXBzdG9uZSBTdHJlZXQsIFRoZSBQb25kcywgTmV3IFNvdXRoIFdhbGVzLCBBdXN0cmFsaWE"
      },
            {
         "full_address": "38 Lapis Crescent, Bardwell Valley, New South Wales, Australia",
         "address_id": "Ej4zOCBMYXBpcyBDcmVzY2VudCwgQmFyZHdlbGwgVmFsbGV5LCBOZXcgU291dGggV2FsZXMsIEF1c3RyYWxpYQ"
      },
            {
         "full_address": "38 Lapish Avenue, Ashfield, New South Wales, Australia",
         "address_id": "EjYzOCBMYXBpc2ggQXZlbnVlLCBBc2hmaWVsZCwgTmV3IFNvdXRoIFdhbGVzLCBBdXN0cmFsaWE"
      },
            {
         "full_address": "38 Lapraik Street, Ascot, Queensland, Australia",
         "address_id": "Ei8zOCBMYXByYWlrIFN0cmVldCwgQXNjb3QsIFF1ZWVuc2xhbmQsIEF1c3RyYWxpYQ"
      },
            {
         "full_address": "38 Lapwing Way, Cranebrook, New South Wales, Australia",
         "address_id": "EjYzOCBMYXB3aW5nIFdheSwgQ3JhbmVicm9vaywgTmV3IFNvdXRoIFdhbGVzLCBBdXN0cmFsaWE"
      }
   ],
   "message_id": "7f4b5f60-0d7c-11e5-ab23-025935216c03"
}